home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 2: CDPD 1 / Almathera Ten on Ten - Disc 2: CDPD 1.iso / pd / 276-300 / 283 / bref / bref.doc < prev    next >
Text File  |  1995-03-14  |  7KB  |  216 lines
  1.     Documentation for Program BREF          Nov 1989   Version 1.01
  2.  
  3.         Dick Taylor  Glastonbury, Connecticut USA
  4.  
  5.  
  6.             Contents
  7.         1. Components
  8.         2. What does BREF do?
  9.         3. Restrictions
  10.         4. How to use
  11.         5. Program history
  12.         6. Program promo
  13.         7. SAVE'ing AmigaBASIC in ASCII
  14.         8. Program limitations
  15.         9. Options
  16.         10. Potential Stack problem
  17.         11. Programming notes
  18.         12. BREF communications
  19.  
  20.  
  21.      -------------------------
  22.     |   E S S E N T I A L S   |
  23.      -------------------------
  24.  
  25.  
  26. 1. COMPONENTS
  27.  
  28. bref     -- executable
  29. bref.c   -- C language source code
  30. bref.doc -- documentation
  31.  
  32.  
  33.  
  34. 2. WHAT DOES BREF DO?
  35.  
  36. BREF produces a Cross Reference Table for AmigaBASIC code.  This consists
  37. of a listing of the BASIC code with lines sequentially numbered, plus a
  38. table showing all variables/labels (names) used in the code and the line
  39. numbers where used.
  40.  
  41.  
  42.  
  43. 3. RESTRICTIONS
  44.  
  45.    a. The AmigaBasic code for input to BREF must be in ASCII format, not the
  46.     default binary.  
  47.    b.  Run BREF from CLI or SHELL.
  48.  
  49.  
  50.  
  51. 4. HOW TO USE
  52.  
  53. Use output redirection   >prt:   to send output to the printer.
  54. In CLI or SHELL:
  55.  
  56.     bref >prt: your.prog.name
  57.  
  58. If you omit output redirection, output goes to the screen.
  59. Specify pathname as needed for both BREF and your program.
  60.  
  61.  
  62.  
  63.  
  64.  
  65.      ---------------------------------------------
  66.     |   B A C K G R O U N D   &   D E T A I L S   |
  67.      ---------------------------------------------
  68.  
  69.  
  70. 5. PROGRAM HISTORY
  71.  
  72.     Program BREF is a modification of CREF, the cross referencer for C
  73. language programs.  I obtained CREF from Fred Fish Disk #166.  The original 
  74. CREF was written in May 1981 by Mike Edmonds, for another computer system.  
  75. CREF was ported to the Amiga in September 1987 by Joel Swank.
  76. In 1989 I modified CREF to produce BREF.
  77.  
  78.  
  79. 6. PROGRAM PROMO
  80.  
  81. BASIC programmers will find BREF to be of interest.  You will need to get
  82. the printed output to attain and appreciate its full usefulness.
  83. Screen output may be useful in some situations.  If you haven't used a
  84. Cross Referencer before, please accept my recomendation that this is a
  85. HIGHLY VALUABLE PROGRAMMING TOOL for any program longer than a page or two.
  86. Cross Referencing Table is a widely available option on many main-frame
  87. compilers, and is a heavily used tool among professional programmers.
  88.  
  89.     (Memo to Commodore/Microsoft:  You could make a substantial
  90.     enhancement to AmigaBASIC by supplying a BASIC Cross Reference
  91.     Utility with one of the Operating System updates.  Until this
  92.     is available, BREF can be used for this function.)
  93.  
  94.  
  95. 7. SAVE'ing AMIGABASIC IN ASCII
  96.  
  97. In order to use BREF, you need to save your BASIC code in ASCII.  Use the
  98. BASIC output window for this:
  99.  
  100.     SAVE "your.prog.name",A
  101.  
  102. Those double quotes are needed, just as shown.  You can't save in ASCII
  103. from the "SAVE" or "SAVE AS" requester windows.  To save on disk space, I
  104. often save the ASCII version to RAM.  For instance:
  105.  
  106.     SAVE "ram:your.prog.name",A
  107.  
  108. Of course, then be sure to include the pathname ram: in starting BREF.  The
  109. default format for saved AmigaBASIC code is binary.  If you try to run BREF
  110. with saved binary, the run aborts with this message:
  111.  
  112.     "File your.prog.name is binary, can't process.  ASCII req."
  113.  
  114.  
  115. 8. PROGRAM LIMITATIONS
  116.  
  117.    a.  AmigaBASIC allows names up to 40 characters in length.  Program BREF,
  118.    however, handles names only up to 15 characters long.  This causes names
  119.    of more than 15 characters to be split, appearing as more than one name in
  120.    the cross reference table.
  121.  
  122.    b.  BREF uses up to four digits (9999) for the sequential line numbers
  123.    assigned to the code listing.  This is sufficient for a listing of 180+
  124.    pages.  Hopefully this will accomodate 99.9% of BASIC programs!  If you
  125.    want to use BREF on a program larger than 9,999 lines, you'll need to
  126.    split it into parts.
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133. 9. OPTIONS
  134.  
  135. The first letter of each option may be upper or lower case.  Here is an
  136. example of running BREF with options:
  137.  
  138.     bref >prt: -Q -W132 your.prog.name
  139.  
  140. Specify as many options as needed; place preceding the program name, any 
  141. order.  Precede each option with a minus sign.
  142.  
  143. -Q    -don't print the BASIC code listing (Quiet).
  144. -Wnnn    -set page Width to nnn instead of default 80; max is 132.
  145. -Lnnn    -set page Length to nnn instead of default 66.
  146. -Hccc    -set page Heading to 'ccc' rather than the program name.
  147. -S    -Suppress Form Feeds; useful for screen output.
  148. -K    -show the BASIC Keywords in the the cross ref table.
  149.      Default-- the BASIC keywords are omitted.
  150. -E    -print the BASIC code 12 char's/inch (Elite type) instead of
  151.      the default 10 char's/inch.  For a default 80-char
  152.      line, this produces a 96-char line.  This tends to cut down on 
  153.      the annoying lines which are split into 2 lines on printing.
  154. -?    -display this list.
  155.  
  156. A single invocation of BREF may specify multiple program names.  Example:
  157.  
  158.     bref >prt: program1 program2 ...
  159.  
  160. This produces one cross reference table for the specified programs. 
  161. Alternatively, the program name(s) as shown may be omitted, and then BREF
  162. reads STDIN for its input.  In this case use input redirection.  Example:
  163.  
  164.     bref <your.prog.name >prt:
  165.  
  166. For this case, the options follow >prt:.
  167.  
  168.  
  169. 10. POTENTIAL STACK PROBLEM
  170.  
  171. BREF makes heavy use of recursion, which is a stack-intensive operation. 
  172. In running very large BASIC programs through BREF, it is possible that you
  173. may crash the system (guru or whatever) due to exceeding the stack (default
  174. stack size is 4000).  If this happens, try increasing the stack to 8000 and
  175. rerun.  The largest program I have run is a little over 1,000 lines-- no
  176. problem with the default stack.
  177.  
  178.  
  179. 11. PROGRAMMING NOTES
  180.  
  181.   a. BREF was compiled with Manx Aztec C v. 3.6:
  182.     cc bref.c
  183.     ln bref.o -lc
  184.   b. Program changes to CREF to produce BREF:
  185.     -AmigaBASIC keyword list, 202 items
  186.     -Char set for word definition: drop # _  add . % & ! # $
  187.     -Comment definition: ' or REM
  188.     -Default print line 80 char (was 132)
  189.     -Add options -S, -K, -E
  190.     -Assigned line no. print field width 4 char (was 6)
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.   c. I encountered significant trouble with implementing the AmigaBASIC
  200. keyword list.  When I entered the list in alphabetic order and tried to run
  201. with stack = 4000, it crashed (guru) in a variety of places depending on
  202. other system factors.  It turns out to be a problem caused by heavy
  203. recursion usage -- entering items (both keywords and program words) into a
  204. tree.  The solution was to enter the keywords in binary search order,
  205. thereby minimizing recursion level depth.  With this arrangement of
  206. keywords I've had no problem running with stack of 4000.
  207.  
  208.  
  209. 12. FOR BREF COMMUNICATIONS--
  210.  
  211.     Dick Taylor        Found a bug?
  212.     99 Valley View Rd    Want a program change?
  213.     Glastonbury CT 06033    Editorial remarks?
  214.     USA            Your comments are welcome!!!
  215.     Tel (203) 633-0100
  216.